 -----------------------------------------
| Patterns of the V_2-polynomial of knots |
 -----------------------------------------

This is the data and code accompanying the paper Patterns of the V_2-polynomial of Knots 
by Stavros Garoufalidis and Shana Yunsheng Li (arXiv:2409.03557)

 ------
| Code |
 ------

We use two languages, Mathematica and Python, as our coding languages, and their codes are stored under /mathematica/ and /python/ respecitvely.
All codes in Mathematica are stored in two different formats: Wolfram Notebook (.nb) and Wolfram Mathematica Package (.m).
The Wolfram Notebook files contain example codes which explains the methods, 
and the Wolfram Mathematica Package files are for easy importation and/or usage within command-line terminals. 

 --------------------
| LVPoly and LinkRot |
 --------------------

Our main method of computing the Vn polynomials, defined as in Section 2 of the paper, is implemented in Mathematica as LVPoly. 
Although mainly used for knots in the paper, LVPoly is compatible with links (hence the L in its name).

LVPoly contains the method LinkRot, which we also store separately for standalone usage, as promised at the end of Section 2.2.1.
Both LVPoly and LinkRot are dependent on the KnotTheory` package, which is available at The Knot Atlas by Dror Bar-Natan (https://katlas.org/).

 -------------------
| Data Manipulation |
 -------------------

We also provided, in Mathematica, VnSQL for accessing SQLite databases, 
and in Python, csv_to_sql.py for converting CSV files to SQLite databases and Vn_sql.py for accessing SQLite databases.

Let us introduce the data we have, while explaining these codes along the way.

 -----
| CSV |
 -----

The majority of data, the Vn polynomials that we computed listed in Table 2, 
are stored as CSV files under /data/csv/, compressed in bzip2 format. 
The volumes of the files scale up 4 to 5 times after decompression.
For example, V2-data_16c_part-1.csv is about 6.16 GB decompressed.

All CSV files are arranged in the same format, namely they all have the following columns:

    SnapPy Name | KnotTheory Name | PD Code | Genus | Degree of Alexander polynomial | Tightness | Vn Polynomial

where the n in "Vn Polynomial" varies depending on the specific CSV file. 

The names of CSV files specify the set of knots they store. For example:

    V1-data_3-15c.csv stores all knots from 3 to 15 crossings (with n = 1);
    V1-data_16c.csv stores all knots with 16 crossings (with n = 1);
    V1-data_17n-loose.csv stores all nonalternating loose knots with 17 crossings (with n = 1);
    V3-data_V2-equiv_15-16c.csv stores all knots in V2-equivalent tuples of 15 to 16 crossings (with n = 3);

Note that, due to size limitation, V2-data_16c.csv is splitted into V2-data_16c_part-1.csv and V2-data_16c_part-2.csv,
and V1-data_19n-loose.csv is splitted into 8 files, from V1-data_19n-loose_part-1.csv to V1-data_19n-loose_part-8.csv.

 --------
| SQLite |
 --------

The recommended way of reading the data in CSV files is to first convert them into SQLite databases, then access the databases.
We provide the python code csv_to_sql.py for the conversion; see the beginning of csv_to_sql.py for instructions on using it.

To demonstrate how to access the databases created, we give a readily created SQLite database file under /data/ ,

    V-database_3-15c.db 

which contains all data stored in the following CSV files:

    V1-data_3-15c.csv;  V2-data_3-15c.csv;  V3-data_3-14c.csv;  V4-data_3-14c.csv

Decompressed, V-database_3-15c.db has a volume of 5.74 GB.

Both Vn_sql.py and VnSQL can be used for accessing V-database_3-15c.db; 
in fact, they support accessing multiple databases created from the CSV files using csv_to_sql.py. 
Vn_sql.py is required to run under SageMath (https://www.sagemath.org) instead of vanilla python. 

To use either of the code, the user is required to open the files and edit the values of the following variables in them:

    sql_path and schema in Vn_sql.py 

or

    sqlPath and schema in VnSQL (.nb or .m)

sql_path (or sqlPath) should be the folder where all SQLite database files are located, 
and schema is a dictionary (in Python) or an association (in Mathematica) of the following format:

    (In Python)
    { 'SQLite database file name': [ names of tables in the database ] }

    (In Mathematica)
    <| "SQLite database file name" -> { names of tables in the database } |>

For example, setting 

    schema = {'V-database_3-15c.db' : ['V1', 'V2', 'V3', 'V4']}

in Vn_sql.py allows you to read all data stored in the provided V-database_3-15c.db.

The explanation of various methods defined in Vn_sql.py and VnSQL.nb can be found in the files themselves. 

 -----
| TXT |
 -----

We also provide some small .txt files storing miscellaneous lists mentioned in the paper, 
under both /mathematica/ and /python/ as the name conventions of knots are segragated between the two languages.

The files are listed and explained as below:

Python              | Mathematica           | Description
-------------------------------------------------------------------------------------------------------------------------------------
mutants_python.txt  | mutants-mma.txt       | All mutant knots converted from A. Stoimenow's table of mutant knots up to 15 crossings  
                    |                       |    (original data available at https://stoimenov.net/stoimeno/homepage/)
-------------------------------------------------------------------------------------------------------------------------------------
V2_equiv_tuples.txt | V2-equiv-tuples.txt   | All V2-equivalent tuples up to 16 crossings as defined in Section 1.4
-------------------------------------------------------------------------------------------------------------------------------------
flavors.tar.bz2     | flavors.tar.bz2       | Three .txt files, compressed together, of V2-equivalent tuples (up to 16 crossings) 
                    |                       | divided into the three different flavors defined in Section 1.4

In Python convention, each line of the files contain multiple names of knots, separated with commas (,).
If the knot is the mirror of the one stored in knot tables, a prefix Mirror@ is added before the name of the knot
(Warning: Stoimenow's mutant table does not distinguish knots with their mirror images, but our V2_equiv_tuples.txt does)

In Mathematica convention, each file contains a string that represent a list of tuples of knots. 
The files can be recovered into lists in Mathematica with the Get[] function (see https://reference.wolfram.com/language/ref/Get.html) 